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ABSTRACT 



In order to allow for an efficient and flexible scientific 
analysis of data from the SPI imaging spectrometer 
aboard INTEGRAL, I developed a set of analysis 
executables that are publicly available through the 
internet. The software is fully compatible with the 
ISDC data format. It complements software that 
is actually available through ISDC, and will be in- 
cluded in the next ISDC software release. This pa- 
per describes the design of my software system and 
provides a brief introduction to the executables. 

Key words: SPI data analysis; software. 



1. INTRODUCTION 



SPI data analysis is a complex task. The data 
volume is important, the outstanding spectral 
resolution requires an accurate gain calibration, the 
important instrumental background demands a very 
precise modelling of its time variations, and the 
generally weak signals require sophisticated analysis 
methods. To perform SPI data analysis at the 
Centre d'Etude Spatiale des Rayonnements (CESR) 
in Toulouse, I therefore developed an efficient 
data analysis system that builds on the software 
kernel provided by the INTEGRAL Science Data 
Centr e (ISD C). My software is available at the site 
http : //www . cesr . f r/ ^jurgen/ isdc/ index . html 
and will be distributed in future versions of the 
ISDC Offline Science Analysis (OSA) system. At 
CESR, the system has been installed on a UNIX 
machine under Solaris 9, yet ports to Linux systems 
have also been performed successfully (the installa- 
tion procedure is identical to that of regular ISDC 
software) . 

The core of the system is a library of C++ classes 
and functions (spi_toolslib) that provides all nec- 
essary functionalities for data analysis. Around this 
library, a number of analysis executables has been 
written. All software is documented by User Man- 
uals. In particular, the spi_toolslib library is de- 
scribed in great detail, allowing the data analyst to 



easily build new analysis executables using the avail- 
able functions. 

The starting point of the analysis is the prepared 
data provided by ISDC. These data are organised 
by satellite orbital revolutions (one revolution last- 
ing typically three days), and are split into so called 
science windows, which generally either comprise a 
spacecraft pointing or a spacecraft slew. In the cur- 
rent approach only the pointing data are exploited. 

Data analysis consists of 5 steps: observation group 
building, gain calibration, data preparation, data 
combination, scientific analysis (imaging, model fit- 
ting, spectral analysis) In the following sections these 
5 steps are described. 



2. OBSERVATION GROUP BUILDING 



The entity of data that is combined for analysis is 
called an observation group. An observation group 
is a FITS file that contains pointers to all data that 
are associated to the observation. For all executa- 
bles it is sufficient to provide on input an observa- 
tion group, the software then automatically extracts 
the relevant information. Note, however, that the 
observation group contains the access paths to the 
individual data files, hence moving the data may in- 
validate the information stored in the observation 
group. Thus it is recommended not to copy or move 
observation groups or associated data. 

The first step of the analysis consists in building an 
observation group (cf. Fig. Q}. For practical pur- 
poses, I generally build an observation group per 
revolution. This leads to manageable data sizes and 
reasonable execution times for data preparation. In 
addition, this allows for a time-dependent gain cali- 
bration that may compensate detector drifts. 

To gather the available science windows of an 
observation group, I use a UNIX script called 
swg_build_list that collects the Data Object Lo- 
cations (DOLs) of all science window groups into 
a single ASCII file. A science window group is a 
FITS file that contains pointers to the data that are 
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scw/0Q47/004700Q10Q10/swg prp.fits[1] 
scw/0047/004700010021/swg prp.fits[1] 
scw/0047/004700020010/swg prp.fits[1 ] 
scw/0047/00470002002 1 /swg_prp,fits[1 ] 

X7 








og_spi.fits 
swg_idx.fits 

scw/004700010010/swg.fits 
00470001 002 1/swg. fits 
00470002001 0/swg. fits 
004700020021/swg.fits 

spi/ 



Figure 1. Observation Group Building step. A list 
of science windows, specified by the Data Object Lo- 
cations (DOLs) of the science window groups listed 
in an ASCII file, are combined into an observation 
group. This is the starting point for SPI data anal- 
ysis. The resulting data structure is depicted in the 
data container at the bottom of the figure. 



contained within an individual science window. The 
ASCII file is then used as input for the executable 
spi_obs_create which builds the observation group. 
One may edit the ASCII file to exclude individual 
science windows from the analysis. In the current 
system, a science window is the shortest junk of data 
that may be analysed. Analysis of shorter periods, 
e.g. as needed for gamma-ray burst studies, has not 
been implemented so far. 



event histogramming software, which then handles 
the time dependence of the gain calibration. 

Note that gain calibration files and indices are pro- 
vided by ISDC and may also be downloaded on my 
internet site, hence normally the gain calibration 
step is not required for your analysis. 





og_spi.fits 









spt_gain_hist 



spi_cal_spectra.fits 

[SPI.-CAL.-GTT] 
[SPI.-CAL.-DSP] 



sp i_l i ne_def i n ition . fits 

[SPI.-LINE-SCT 



spi_line_fit 



spi_cal_resu Its. fits 

[SPI.-LINE-SRT] 



gainResults.C 

V , J 



n_coeff_0047.fits 
n_coeff_0048.fits 
n_coeff_0049.fits 
n_coeff_0050.fits 
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gainCalib.C 




spi_gain_coeff_index.fits 

[SPI.-COEF-CAL-IDX] 



3. GAIN CALIBRATION 



The next step consists in gain calibration to con- 
vert the registered Pulse-Height Analyser (PHA) val- 
ues for each event into physical meaningful ener- 
gies (cf. Fig. EJ). For this purpose, the line cen- 
troid in PHA units are determined for a couple of 
well selected gamma-ray lines of known energies that 
arise in the instrumental background (see Lonjou 
et al., these proceedings). Spectra of PHA values 
are built for each revolution using the executable 
spi_gain_tiist, and line fitting is performed using 
spi_line_f it. In the actual approach, Gaussian 
shaped lines on top of a linear background are em- 
ployed for fitting (this basically ignores the effect of 
detector degradation which leads to an extension on 
the left wing of the lines). 

From the fitted energies, calibration relations are de- 
rived using the isdcroot scripts gainResults.C and 
gainCalib.C. The calibration relations for each rev- 
olution are then combined in an index table (using 
the ISDC executable txt2idx) that is passed to the 



spi_gain_coeff.fits 

[SPI.-COEF-CAL] 



Figure 2. Gain calibration step. The input obser- 
vation group contains a list of science windows, typ- 
ically those of one satellite revolution. The resulting 
gain coefficient file contains calibration coefficients 
for this list of science windows. The coefficients for 
each revolution are combined into a calibration index 
allowing for time dependent gain correction. 



4. DATA PREPARATION 

The Data Preparation step consists in building the 
3-dimensional SPI data-space for each observation 
group, which is spanned by spacecraft pointing, tele- 
scope detector, and photon energy (cf. Fig.|HJ). This 
data-space is stored in a FITS file with extension 
name SPI . -0BS . -DSP. 

First, the energy binning of the data-space is defined 
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og_spi.fits 



rev0047/og_spi.fits 
rev0048/og_spi.fits 
rev0049/og_spi.fits 
rev0050/og_spi.fits 




og_spi.fits 

spi/energyboundaries.fits [ spi . -ebds-set ] 





og_spi.fits 
$wg_idx.fits 

spi/energy_boundaries.fits [ spi . -ebds-set ] 
spi/pointing.fits [ spi . -obs . -pnt ] 
spi/gti.fits [ spi . -obs . -gti ] 
spi/dead_time.fits [ spi . -obs . -dti ] 
spi/evtsdetspec.fits [ spi . -OBS . -dsp ] 
spi/back_modeljdx.fits [ spi . -bmod-dsp-idx ] 
spi/backjmodel.fits [ spi . -bmod-dsp ] 



ogspi.fits 

spi/pointing.fits [ SPI . -OBS . -PNT ] 



spi_gain_coeff_index.fits 

[ SPI . -COEF-CAL-IDX ] 




og_spi.fits 

spi/gti.fits [ spi . -OBS . -gti ] 
spi/dead_time.fits [ spi . -obs . -dti ] 
spi/evts_det_s pec. fits [ spi . -obs . -dsp ] 




ogspi.fits 

spi/back_model_idx.fits[SPi . -bmod-dsp-idx ] 
spi/backjnodelfits [ spi . -bmod-dsp ] 



spiobsadjust 

V , J 



ogspi.fits 

spi/evts_det_spec.fits [ spi . -obs . -dsp ] 
spi/back_model_idx.fits [ spi . -bmod-dsp-idx ] 
spi/back_model.fits [ spi . -bmod-dsp ] 



Figure 4- Data combination step. A list of prepared 
observation groups are combined into a single obser- 
vation group. Background modelling and degradation 
adjustment may be applied to the combined data. 



As next step, the available spacecraft pointings are 
extracted for an observation group using the ex- 
ecutable spi_obs .point. This executable adds a 
FITS file with extension name SPI . -OBS . -PNT to 
the observation group that contains the start and 
stop time for each pointing, as well as the SPI tele- 
scope pointing direction (the misalignment between 
SPI and the spacecraft is taken into account at this 
step). 

Now the observation group is ready for data- 
space building. This is done using the executable 
spi_obsJiist which adds three FITS files to the 
observation group: SPI . -OBS . -GTI which contains 
the Good Time Intervals for each pointing and 
detector as well as the effective exposure time, 
SPI . -OBS . -DTI which contains the Livetime for each 
pointing and detector, and SPI . -OBS . -DSP which 
contains the histogrammed photon data (in units 
of counts). spi_obs_tiist automatically detects the 
data transmission modes of SPI (operational mode, 
spectral mode or emergency mode), and performs the 
required transformations to provide a homogeneous 
and clean set of prepared data. 



Figure 3. Data preparation step. The input obser- 
vation group contains a list of science windows, the 
output observation group contains calibrated detector 
spectra for each pointing and pseudo- detector with 
the associated pointing, exposure, lifetime and back- 
ground model information. Degradation effects have 
been corrected for. The output observation group is 
now ready for scientific analysis. 



using the executable spibounds which adds a FITS 
file with extension name SPI . -EBDS-SET to the ob- 
servation group that contains the lower and upper 
energy boundary for each of the energy bins. 



Before the data can be analysed, a model of 
the instrumental background is required. Back- 
ground modelling is performed using the executable 
spi_obs_back which adds a list of background model 
components to the observation group (extension 
name SPI . -BMOD-DSP). Note that the background 
model may consist of several components which are 
stored in separate data structures (yet in the same 
FITS file). These data structures are then combined 
by an index table that is attached to the observation 
group (extension name SPI . -BMOD-DSP-IDX). 

Background modelling is of course the most delicate 
step in SPI data analysis, and for more information 
about the available background models the data an- 
alyst is referred to the spi_obs_back User Manual. 
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Finally, differences in the detector degradation be- 
tween the histogrammed data and the background 
model components may be compensated using the 
executable spi_obs_adjust. This step is optional, 
but recommended for gamma-ray line analysis. 



5. DATA COMBINATION 



If the data preparation has been performed 
revolution- wise, the observation groups may now 
be combined using the executable spi_obs_add 
(cf. Fig.^J). Note that in principle several revolutions 
may be prepared in a single step, yet the execution 
time of the histogramming step (spi_obs_tiist) rises 
non-linearly with data-space dimensions (due to the 
particular architecture of the FITS access routines). 

spi_obs_add also allows to select a sub-range of en- 
ergy bins from the input data, leading eventually 
to smaller and more manageable data-space dimen- 
sions. Background modelling (spi_obs_back) and 
degradation adjustment (spi.obs .adjust) may also 
be performed after data combination using the out- 
put observation group of spi_obs_add as input. This 
allows testing different background models and/or 
degradation corrections for the same data. 



6. SCIENTIFIC ANALYSIS 



og_spi.fits 



spi_response_group.fits 
[SPI.-IRF.-GRP] 



spi_obs_fit 



og_spi.fits 

energy boundaries. fits [ spi . -ebds-set ] 
evts_det_spec.fits [ spi . -obs . -DSP ] 
back_rnodel_idx.fits[SPi . -bmod-dsp-idx] 
back_model.fits[SPi . -bmod-dsp] 
results.fits [ spi . -srcl-res ] 
source_model_idx,fits [ spi . -SRC . -dsp-idx ] 
sourcejnodel.fits [ spi . -src . -dsp ] 
imagejdx.fits [ spi . -sky . -ima-idx ] 
image.fits [ spi . -sky . -ima] 



100.0 1.0 1.01 0.02 345 23.0 .. 

101.0 1.0 0.94 0.03 312.0 26.0 .. 

102.0 1.0 1.03 0.03 317.0 22.0 .. 

103.0 1.0 0.90 0.02 360.0 27.0 .. 



og_spi.fits 



spi_response_group.fits 

[SPI.-IRF.-GRP] 



spiobsmrem 



og_spi.fits 

energy_boundaries.fits [ SPI . -EBDS-SET ] 
evts_det_spec.fits [ spi . -obs . -DSP ] 
back model idx.fits [ spi . -bmod-dsp-idx ] 
back_model.fits [ spi . -bmod-dsp ] 
imagejdx.fits [ spi , -sky.-ima-idx] 
image.fits [ spi . -sky . -ima] 



1 2567.0 1.01 0.02 345.0 23.0 .. 

2 2400.7 94 0.03 312.0 26.0 .. 

3 2300.2 1.03 0.03 317.0 22.0 .. 

4 2100.7 0.90 0.02 360,0 27.0 .. 



Now, scientific analysis executables provided by 
ISDC, such as spiros for point-source localisation 
and spectral analysis, may be applied to the pre- 
pared data. In my system, two further executables 
are available (cf. Fig. 0). spi_obs_fit performs fit- 
ting of sky-intensity distributions to the data, al- 
lowing for morphology studies and spectral analysis. 
Various treatments of the instrumental background 
are provided, allowing for reduction of the systematic 
uncertainties in the data analysis. 

spi_obs_mrem performs Expectation Maximisation 
image deconvolutions to extract sky-intensity distri- 
butions from the data. The implemented algorithm 
is also known as accelerated Richardson-Lucy algo- 
rithm, and has proven successful for the analysis of 
gamma-ray data for other missions. In the future, it 
is foreseen to implement also a Multiresolution anal- 
ysis in this software, allowing to reduce statistical 
artefacts in the reconstructed intensity distributions 
for diffuse emission. 

Both executables produce on output an observation 
group that contains the data that have been used 
for analysis. This means that if for example only a 
single energy bin has been selected for imaging anal- 
ysis, the resulting observation group contains only 
the data and background model for this single en- 
ergy bin. Or if the background model has been mod- 
ified by spi_obs_fit during the fitting procedure, 
the resulting background model with the scaling fac- 
tors applied will be stored in the output observation 



Figure 5. Scientific analysis step. The instrument 
response is used in this step. On output, an observa- 
tion group is created that contains all data that have 
been used for the scientific analysis. An ASCII file 
contains the analysis results for quick display. 

group. In a following step, this output observation 
group may then be used for example for imaging. 

spi_obs_f it provides also an image on output which 
contains the best fitting combination of the model 
components that have been fitted to the data. In this 
way, a model intensity distribution can be derived 
from the data. 



7. CONCLUSIONS 



The software described in this article has been de- 
signed and coded to allow for an efficient and flex- 
ible scientific analysis of SPI data. I hope that the 
present article is particularly useful for INTEGRAL 
guest observers, and that the information provided 
will increase the reliability of the data analysis per- 
formed by non experts. Providing simple and robust 
software to the user community is certainly a pre- 
requisite for the success of the INTEGRAL mission, 
hopefully allowing to achieve many new and inter- 
esting science results. 



